/**
 * 
 */
package org.stars.security;

import java.io.Serializable;
import java.util.Set;

/**
 * Questa interfaccia rappresenta un utente che si è identificato presso il sistema.
 * Sono presenti i metodi di base che permettono di individuare quali abilitazioni
 * ha un utente.
 * 
 * @author Francesco Benincasa (908099)
 * 
 */
public interface UserIdentity extends Serializable {
		
	/**
	 * Verifica se l'utente è abilitato ad una funzione.
	 * La funzione viene rappresentata dal suo nome. Il nome della funzione è case
	 * insensitive.
	 * 
	 * @param functionName
	 * 			nome della funzione
	 * @return
	 * 			<code>true</code> se l'utente è abilitato alla funzione richiesta, <code>false<code> altrimenti.
	 */
	boolean isEnableTo(String functionName);

	/**
	 * Verifica se "l'identità" fornita rappresenta effettivamente uno "user" valido per
	 * il contesto applicativo in cui lo si usa
	 * @return
	 * 			<code>true</code> se l'identità risulta "valida", <code>false<code> altrimenti.
	 */
	boolean isIdentityValid();

	/**
	 * Verifica se l'utente possiede un determinato ruolo.
	 * Il ruolo viene rappresentato dal suo nome. Il nome del ruolo è case insentive.
	 * 
	 * @param roleName
	 * 			nome del ruolo
	 * @return
	 * 			<code>true</code> se l'utente possiede il ruolo richiesto, <code>false<code> altrimenti.
	 */
	boolean hasRole(String roleName);

	/**
	 * Restituisce il valore di un attributo associato ad un utente. Nel caso in cui
	 * l'attributo non esiste, viene restituito <code>null</code>. Il nome dell'attributo è
	 * case insentive.
	 * 
	 * @param attributeName
	 * 			nome dell'attributo
	 * @return
	 * 			valore dell'attributo o <code>null</code> nel caso esso non esista.
	 */
	Object getAttribute(String attributeName);

	/**
	 * Imposta un attributo per un utente. L'attributo viene memorizzato nella sessione, non viene
	 * memorizzato a livello di base dati centrale.
	 * 
	 * @param attributeName
	 * 			nome dell'attributo
	 * @param value
	 * 			nuovo valore dell'attributo
	 */
	void setAttribute(String attributeName, Object value);

	/**
	 * Restituisce il nome dell'utente.
	 * 
	 * @return
	 * 		nome dell'utente
	 */
	String getUsername();

	/**
	 * Restituisce la descrizione dell'utente, tipicamente il nome ed il cognome.
	 * 
	 * @return
	 * 		descrizione dell'utente
	 */
	String getDescription();

	/**
	 * Restituisce l'elenco dei ruoli ai quali l'utente è stato abilitato.
	 * 
	 * @return
	 * 		elenco dei ruoli
	 */
	Set<String> getRoles();

	/**
	 * Restituisce l'elenco delle funzioni alle quali l'utente è abilitato.
	 * 
	 * @return
	 * 		elenco delle funzioni
	 */
	Set<String> getFunctions();

	/**
	 * E' l'oggetto user memorizzato in sessione.
	 * Il suo tipo è it.insiel.websecurity.User
	 */
    static final String SESSION_NAME="user";

}
